home *** CD-ROM | disk | FTP | other *** search
/ SGI Developer Toolbox 6.1 / SGI Developer Toolbox 6.1 - Disc 4.iso / public / GNU / emacs.inst / emacs19.idb / usr / gnu / info / elisp-16.z / elisp-16
Encoding:
GNU Info File  |  1994-08-02  |  50.5 KB  |  1,212 lines
  1. This is Info file elisp, produced by Makeinfo-1.55 from the input file
  2. elisp.texi.
  3.  
  4.    This version is newer than the second printed edition of the GNU
  5. Emacs Lisp Reference Manual.  It corresponds to Emacs Version 19.19.
  6.  
  7.    Published by the Free Software Foundation 675 Massachusetts Avenue
  8. Cambridge, MA 02139 USA
  9.  
  10.    Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
  11.  
  12.    Permission is granted to make and distribute verbatim copies of this
  13. manual provided the copyright notice and this permission notice are
  14. preserved on all copies.
  15.  
  16.    Permission is granted to copy and distribute modified versions of
  17. this manual under the conditions for verbatim copying, provided that
  18. the entire resulting derived work is distributed under the terms of a
  19. permission notice identical to this one.
  20.  
  21.    Permission is granted to copy and distribute translations of this
  22. manual into another language, under the above conditions for modified
  23. versions, except that this permission notice may be stated in a
  24. translation approved by the Foundation.
  25.  
  26.    Permission is granted to copy and distribute modified versions of
  27. this manual under the conditions for verbatim copying, provided also
  28. that the section entitled "GNU Emacs General Public License" is included
  29. exactly as in the original, and provided that the entire resulting
  30. derived work is distributed under the terms of a permission notice
  31. identical to this one.
  32.  
  33.    Permission is granted to copy and distribute translations of this
  34. manual into another language, under the above conditions for modified
  35. versions, except that the section entitled "GNU Emacs General Public
  36. License" may be included in a translation approved by the Free Software
  37. Foundation instead of in the original English.
  38.  
  39. 
  40. File: elisp,  Node: Scanning Keymaps,  Prev: Key Binding Commands,  Up: Keymaps
  41.  
  42. Scanning Keymaps
  43. ================
  44.  
  45.    This section describes functions used to scan all the current keymaps
  46. for the sake of printing help information.
  47.  
  48.  - Function: accessible-keymaps KEYMAP &optional PREFIX
  49.      This function returns a list of all the keymaps that can be
  50.      accessed (via prefix keys) from KEYMAP.  The value is an
  51.      association list with elements of the form `(KEY . MAP)', where
  52.      KEY is a prefix key whose definition in KEYMAP is MAP.
  53.  
  54.      The elements of the alist are ordered so that the KEY increases in
  55.      length.  The first element is always `("" . KEYMAP)', because the
  56.      specified keymap is accessible from itself with a prefix of no
  57.      events.
  58.  
  59.      If PREFIX is given, it should be a prefix key sequence; then
  60.      `accessible-keymaps' includes only the submaps whose prefixes start
  61.      with PREFIX.  These elements look just as they do in the value of
  62.      `(accessible-keymaps)'; the only difference is that some elements
  63.      are omitted.
  64.  
  65.      In the example below, the returned alist indicates that the key
  66.      ESC, which is displayed as `^[', is a prefix key whose definition
  67.      is the sparse keymap `(keymap (83 . center-paragraph) (115 .
  68.      foo))'.
  69.  
  70.           (accessible-keymaps (current-local-map))
  71.           =>(("" keymap
  72.                 (27 keymap   ; Note this keymap for ESC is repeated below.
  73.                     (83 . center-paragraph)
  74.                     (115 . center-line))
  75.                 (9 . tab-to-tab-stop))
  76.  
  77.           ("^[" keymap
  78.               (83 . center-paragraph)
  79.               (115 . foo)))
  80.  
  81.      In the following example, `C-h' is a prefix key that uses a sparse
  82.      keymap starting with `(keymap (118 . describe-variable)...)'.
  83.      Another prefix, `C-x 4', uses a keymap which happens to be
  84.      `ctl-x-4-map'.  The event `mode-line' is one of several dummy
  85.      events used as prefixes for mouse actions in special parts of a
  86.      window.
  87.  
  88.           (accessible-keymaps (current-global-map))
  89.           => (("" keymap [set-mark-command beginning-of-line ...
  90.                              delete-backward-char])
  91.  
  92.           ("^H" keymap (118 . describe-variable) ...
  93.                (8 . help-for-help))
  94.  
  95.           ("^X" keymap [x-flush-mouse-queue ...
  96.                backward-kill-sentence])
  97.  
  98.           ("^[" keymap [mark-sexp backward-sexp ...
  99.                backward-kill-word])
  100.               ("^X4" keymap (15 . display-buffer) ...)
  101.           ([mode-line] keymap
  102.                (S-mouse-2 . mouse-split-window-horizontally) ...))
  103.  
  104.      These are not all the keymaps you would see in an actual case.
  105.  
  106.  - Function: where-is-internal COMMAND &optional KEYMAP FIRSTONLY
  107.      This function returns a list of key sequences (of any length) that
  108.      are bound to COMMAND in KEYMAP and the global keymap.  The
  109.      argument COMMAND can be any object; it is compared with all keymap
  110.      entries using `eq'.  If KEYMAP is not supplied, then the global
  111.      map alone is used.
  112.  
  113.      If FIRSTONLY is non-`nil', then the value is a single string
  114.      representing the first key sequence found, rather than a list of
  115.      all possible key sequences.
  116.  
  117.      This function is used by `where-is' (*note Help: (emacs)Help.).
  118.  
  119.           (where-is-internal 'describe-function)
  120.               => ("\^hf" "\^hd")
  121.  
  122.  - Command: describe-bindings PREFIX
  123.      This function creates a listing of all defined keys, and their
  124.      definitions.  The listing is put in a buffer named `*Help*', which
  125.      is then displayed in a window.
  126.  
  127.      A meta character is shown as ESC followed by the corresponding
  128.      non-meta character.  Control characters are indicated with `C-'.
  129.  
  130.      When several characters with consecutive ASCII codes have the same
  131.      definition, they are shown together, as `FIRSTCHAR..LASTCHAR'.  In
  132.      this instance, you need to know the ASCII codes to understand
  133.      which characters this means.  For example, in the default global
  134.      map, the characters `SPC .. ~' are described by a single line.
  135.      SPC is ASCII 32, `~' is ASCII 126, and the characters between them
  136.      include all the normal printing characters, (e.g., letters,
  137.      digits, punctuation, etc.); all these characters are bound to
  138.      `self-insert-command'.
  139.  
  140.      If PREFIX is non-`nil', it should be a prefix key; then only keys
  141.      that start with PREFIX are described.
  142.  
  143. 
  144. File: elisp,  Node: Modes,  Next: Documentation,  Prev: Keymaps,  Up: Top
  145.  
  146. Major and Minor Modes
  147. *********************
  148.  
  149.    A "mode" is a set of definitions that customize Emacs and can be
  150. turned on and off while you edit.  There are two varieties of modes:
  151. "major modes", which are mutually exclusive and used for editing
  152. particular kinds of text, and "minor modes", which provide features that
  153. may be enabled individually.
  154.  
  155.    This chapter covers both major and minor modes, the way they are
  156. indicated in the mode line, and how they run hooks supplied by the user.
  157. Related topics such as keymaps and syntax tables are covered in separate
  158. chapters.  (*Note Keymaps::, and *Note Syntax Tables::.)
  159.  
  160. * Menu:
  161.  
  162. * Major Modes::        Defining major modes.
  163. * Minor Modes::        Defining minor modes.
  164. * Mode Line Format::   Customizing the text that appears in the mode line.
  165. * Hooks::              How to use hooks; how to write code that provides hooks.
  166.  
  167. 
  168. File: elisp,  Node: Major Modes,  Next: Minor Modes,  Prev: Modes,  Up: Modes
  169.  
  170. Major Modes
  171. ===========
  172.  
  173.    Major modes specialize Emacs for editing particular kinds of text.
  174. Each buffer has only one major mode at a time.
  175.  
  176.    The least specialized major mode is called "Fundamental mode".  This
  177. mode has no mode-specific definitions or variable settings, so each
  178. Emacs command behaves in its default manner, and each option is in its
  179. default state.  All other major modes redefine various keys and options.
  180. For example, Lisp Interaction mode provides special key bindings for
  181. LFD (`eval-print-last-sexp'), TAB (`lisp-indent-line'), and other keys.
  182.  
  183.    When you need to write several editing commands to help you perform a
  184. specialized editing task, creating a new major mode is usually a good
  185. idea.  In practice, writing a major mode is easy (in contrast to
  186. writing a minor mode, which is often difficult).
  187.  
  188.    If the new mode is similar to an old one, it is often unwise to
  189. modify the old one to serve two purposes, since it may become harder to
  190. use and maintain.  Instead, copy and rename an existing major mode
  191. definition and alter it for its new function.  For example, Rmail Edit
  192. mode, which is in `emacs/lisp/rmailedit.el', is a major mode that is
  193. very similar to Text mode except that it provides three additional
  194. commands.  Its definition is distinct from that of Text mode, but was
  195. derived from it.
  196.  
  197.    Rmail Edit mode is an example of a case where one piece of text is
  198. put temporarily into a different major mode so it can be edited in a
  199. different way (with ordinary Emacs commands rather than Rmail).  In such
  200. cases, the temporary major mode usually has a command to switch back to
  201. the buffer's usual mode (Rmail mode, in this case).  You might be
  202. tempted to present the temporary redefinitions inside a recursive edit
  203. and restore the usual ones when the user exits; but this is a bad idea
  204. because it constrains the user's options when it is done in more than
  205. one buffer: recursive edits must be exited most-recently-entered first.
  206. Using alternative major modes avoids this limitation.  *Note Recursive
  207. Editing::.
  208.  
  209.    The standard GNU Emacs Lisp library directory contains the code for
  210. several major modes, in files including `text-mode.el', `texinfo.el',
  211. `lisp-mode.el', `c-mode.el', and `rmail.el'.  You can look at these
  212. libraries to see how modes are written.  Text mode is perhaps the
  213. simplest major mode aside from Fundamental mode.  Rmail mode is a
  214. rather complicated, full-featured mode.
  215.  
  216. * Menu:
  217.  
  218. * Major Mode Conventions::  Coding conventions for keymaps, etc.
  219. * Example Major Modes::     Text mode and Lisp modes.
  220. * Auto Major Mode::         How Emacs chooses the major mode automatically.
  221. * Mode Help::               Finding out how to use a mode.
  222.  
  223. 
  224. File: elisp,  Node: Major Mode Conventions,  Next: Example Major Modes,  Prev: Major Modes,  Up: Major Modes
  225.  
  226. Major Mode Conventions
  227. ----------------------
  228.  
  229.    The code for existing major modes follows various coding conventions,
  230. including conventions for local keymap and syntax table initialization,
  231. global names, and hooks.  Please keep these conventions in mind when you
  232. create a new major mode:
  233.  
  234.    * Define a command whose name ends in `-mode', with no arguments,
  235.      that switches to the new mode in the current buffer.  This command
  236.      should set up the keymap, syntax table, and local variables in an
  237.      existing buffer without changing the buffer's text.
  238.  
  239.    * Write a documentation string for this command which describes the
  240.      special commands available in this mode.  `C-h m'
  241.      (`describe-mode') will print this.
  242.  
  243.      The documentation string may include the special documentation
  244.      substrings, `\[COMMAND]', `\{KEYMAP}', and `\<KEYMAP>', that
  245.      enable the documentation to adapt automatically to the user's own
  246.      key bindings.  *Note Keys in Documentation::.  The `describe-mode'
  247.      function replaces these special documentation substrings with
  248.      their current meanings.  *Note Accessing Documentation::.
  249.  
  250.    * The major mode command should set the variable `major-mode' to the
  251.      major mode command symbol.  This is how `describe-mode' discovers
  252.      which documentation to print.
  253.  
  254.    * The major mode command should set the variable `mode-name' to the
  255.      "pretty" name of the mode, as a string.  This appears in the mode
  256.      line.
  257.  
  258.    * Since all global names are in the same name space, all the global
  259.      variables, constants, and functions that are part of the mode
  260.      should have names that start with the major mode name (or with an
  261.      abbreviation of it if the name is long).  *Note Style Tips::.
  262.  
  263.    * The major mode should usually have its own keymap, which is used
  264.      as the local keymap in all buffers in that mode.  The major mode
  265.      function should call `use-local-map' to install this local map.
  266.      *Note Active Keymaps::, for more information.
  267.  
  268.      This keymap should be kept in a global variable named
  269.      `MODENAME-mode-map'.  Normally the library that defines the mode
  270.      sets this variable.  Use `defvar' to set the variable, so that it
  271.      is not reinitialized if it already has a value.  (Such
  272.      reinitialization could discard customizations made by the user.)
  273.  
  274.    * The mode may have its own syntax table or may share one with other
  275.      related modes.  If it has its own syntax table, it should store
  276.      this in a variable named `MODENAME-mode-syntax-table'.  The reasons
  277.      for this are the same as for using a keymap variable.  *Note
  278.      Syntax Tables::.
  279.  
  280.    * The mode may have its own abbrev table or may share one with other
  281.      related modes.  If it has its own abbrev table, it should store
  282.      this in a variable named `MODENAME-mode-abbrev-table'.  *Note
  283.      Abbrev Tables::.
  284.  
  285.    * To give a variable a buffer-local binding, use
  286.      `make-local-variable' in the major mode command, not
  287.      `make-variable-buffer-local'.  The latter function would make the
  288.      variable local to every buffer in which it is subsequently set,
  289.      which would affect buffers that do not use this mode.  It is
  290.      undesirable for a mode to have such global effects.  *Note
  291.      Buffer-Local Variables::.
  292.  
  293.    * If hooks are appropriate for the mode, the major mode command
  294.      should run the hooks after completing all other initialization so
  295.      the user may further customize any of the settings.  *Note Hooks::.
  296.  
  297.    * If this mode is appropriate only for specially-prepared text, then
  298.      the major mode command symbol should have a property named
  299.      `mode-class' with value `special', put on as follows:
  300.  
  301.           (put 'funny-mode 'mode-class 'special)
  302.  
  303.      This tells Emacs that new buffers created while the current buffer
  304.      has Funny mode should not inherit Funny mode.  Modes such as
  305.      Dired, Rmail, and Buffer List use this feature.
  306.  
  307.    * If it is desirable that Emacs use the new mode by default after
  308.      visiting files with certain recognizable names, add an element to
  309.      `auto-mode-alist' to select the mode for those file names.  If you
  310.      define the mode command to autoload, you should add this element
  311.      in the same file that calls `autoload'.  Otherwise, it is
  312.      sufficient to add the element in the file that contains the mode
  313.      definition.  *Note Auto Major Mode::.
  314.  
  315.    * In the documentation, you should provide a sample `autoload' form
  316.      and an example of how to add to `auto-mode-alist', that users can
  317.      include in their `.emacs' files.
  318.  
  319.    * The top level forms in the file defining the mode should be
  320.      written so that they may be evaluated more than once without
  321.      adverse consequences.  Even if you never load the file more than
  322.      once, someone else will.
  323.  
  324. 
  325. File: elisp,  Node: Example Major Modes,  Next: Auto Major Mode,  Prev: Major Mode Conventions,  Up: Major Modes
  326.  
  327. Major Mode Examples
  328. -------------------
  329.  
  330.    Text mode is perhaps the simplest mode besides Fundamental mode.
  331. Here are excerpts from  `text-mode.el' that illustrate many of the
  332. conventions listed above:
  333.  
  334.      ;; Create mode-specific tables.
  335.      (defvar text-mode-syntax-table nil
  336.        "Syntax table used while in text mode.")
  337.  
  338.      (if text-mode-syntax-table
  339.          ()              ; Do not change the table if it is already set up.
  340.        (setq text-mode-syntax-table (make-syntax-table))
  341.        (modify-syntax-entry ?\" ".   " text-mode-syntax-table)
  342.        (modify-syntax-entry ?\\ ".   " text-mode-syntax-table)
  343.        (modify-syntax-entry ?' "w   " text-mode-syntax-table))
  344.  
  345.      (defvar text-mode-abbrev-table nil
  346.        "Abbrev table used while in text mode.")
  347.      (define-abbrev-table 'text-mode-abbrev-table ())
  348.  
  349.      (defvar text-mode-map nil)   ; Create a mode-specific keymap.
  350.      
  351.      (if text-mode-map
  352.          ()              ; Do not change the keymap if it is already set up.
  353.        (setq text-mode-map (make-sparse-keymap))
  354.        (define-key text-mode-map "\t" 'tab-to-tab-stop)
  355.        (define-key text-mode-map "\es" 'center-line)
  356.        (define-key text-mode-map "\eS" 'center-paragraph))
  357.  
  358.    Here is the complete major mode function definition for Text mode:
  359.  
  360.      (defun text-mode ()
  361.        "Major mode for editing text intended for humans to read.
  362.       Special commands: \\{text-mode-map}
  363.  
  364.      Turning on text-mode runs the hook `text-mode-hook'."
  365.        (interactive)
  366.        (kill-all-local-variables)
  367.  
  368.      (use-local-map text-mode-map)     ; This provides the local keymap.
  369.        (setq mode-name "Text")           ; This name goes into the mode line.
  370.        (setq major-mode 'text-mode)      ; This is how `describe-mode'
  371.                                          ;   finds the doc string to print.
  372.        (setq local-abbrev-table text-mode-abbrev-table)
  373.        (set-syntax-table text-mode-syntax-table)
  374.        (run-hooks 'text-mode-hook))      ; Finally, this permits the user to
  375.                                          ;   customize the mode with a hook.
  376.  
  377.    The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp
  378. Interaction mode) have more features than Text mode and the code is
  379. correspondingly more complicated.  Here are excerpts from
  380. `lisp-mode.el' that illustrate how these modes are written.
  381.  
  382.      ;; Create mode-specific table variables.
  383.      (defvar lisp-mode-syntax-table nil "")
  384.      (defvar emacs-lisp-mode-syntax-table nil "")
  385.      (defvar lisp-mode-abbrev-table nil "")
  386.  
  387.      (if (not emacs-lisp-mode-syntax-table) ; Do not change the table
  388.                                             ;   if it is already set.
  389.          (let ((i 0))
  390.            (setq emacs-lisp-mode-syntax-table (make-syntax-table))
  391.  
  392.      ;; Set syntax of chars up to 0 to class of chars that are
  393.            ;;   part of symbol names but not words.
  394.            ;;   (The number 0 is `48' in the ASCII character set.)
  395.            (while (< i ?0)
  396.              (modify-syntax-entry i "_   " emacs-lisp-mode-syntax-table)
  397.              (setq i (1+ i)))
  398.            ...
  399.  
  400.      ;; Set the syntax for other characters.
  401.            (modify-syntax-entry ?  "    " emacs-lisp-mode-syntax-table)
  402.            (modify-syntax-entry ?\t "    " emacs-lisp-mode-syntax-table)
  403.            ...
  404.  
  405.      (modify-syntax-entry ?\( "()  " emacs-lisp-mode-syntax-table)
  406.            (modify-syntax-entry ?\) ")(  " emacs-lisp-mode-syntax-table)
  407.            ...))
  408.      ;; Create an abbrev table for lisp-mode.
  409.      (define-abbrev-table 'lisp-mode-abbrev-table ())
  410.  
  411.    Much code is shared among the three Lisp modes.  The following
  412. function sets various variables; it is called by each of the major Lisp
  413. mode functions:
  414.  
  415.      (defun lisp-mode-variables (lisp-syntax)
  416.        ;; The `lisp-syntax' argument is `nil' in Emacs Lisp mode,
  417.        ;;   and `t' in the other two Lisp modes.
  418.        (cond (lisp-syntax
  419.               (if (not lisp-mode-syntax-table)
  420.                   ;; The Emacs Lisp mode syntax table always exists, but
  421.                   ;;   the Lisp Mode syntax table is created the first time a
  422.                   ;;   mode that needs it is called.  This is to save space.
  423.  
  424.      (progn (setq lisp-mode-syntax-table
  425.                             (copy-syntax-table emacs-lisp-mode-syntax-table))
  426.                          ;; Change some entries for Lisp mode.
  427.                          (modify-syntax-entry ?\| "\"   "
  428.                                               lisp-mode-syntax-table)
  429.                          (modify-syntax-entry ?\[ "_   "
  430.                                               lisp-mode-syntax-table)
  431.                          (modify-syntax-entry ?\] "_   "
  432.                                               lisp-mode-syntax-table)))
  433.  
  434.      (set-syntax-table lisp-mode-syntax-table)))
  435.        (setq local-abbrev-table lisp-mode-abbrev-table)
  436.        ...)
  437.  
  438.    Functions such as `forward-paragraph' use the value of the
  439. `paragraph-start' variable.  Since Lisp code is different from ordinary
  440. text, the `paragraph-start' variable needs to be set specially to
  441. handle Lisp.  Also, comments are indented in a special fashion in Lisp
  442. and the Lisp modes need their own mode-specific
  443. `comment-indent-function'.  The code to set these variables is the rest
  444. of `lisp-mode-variables'.
  445.  
  446.      (make-local-variable 'paragraph-start)
  447.        (setq paragraph-start (concat "^$\\|" page-delimiter))
  448.        ...
  449.  
  450.      (make-local-variable 'comment-indent-function)
  451.        (setq comment-indent-function 'lisp-comment-indent))
  452.  
  453.    Each of the different Lisp modes has a slightly different keymap.
  454. For example, Lisp mode binds `C-c C-l' to `run-lisp', but the other
  455. Lisp modes do not.  However, all Lisp modes have some commands in
  456. common.  The following function adds these common commands to a given
  457. keymap.
  458.  
  459.      (defun lisp-mode-commands (map)
  460.        (define-key map "\e\C-q" 'indent-sexp)
  461.        (define-key map "\177" 'backward-delete-char-untabify)
  462.        (define-key map "\t" 'lisp-indent-line))
  463.  
  464.    Here is an example of using `lisp-mode-commands' to initialize a
  465. keymap, as part of the code for Emacs Lisp mode.  First we declare a
  466. variable with `defvar' to hold the mode-specific keymap.  When this
  467. `defvar' executes, it sets the variable to `nil' if it was void.  Then
  468. we set up the keymap if the variable is `nil'.
  469.  
  470.    This code avoids changing the keymap or the variable if it is already
  471. set up.  This lets the user customize the keymap if he or she so wishes.
  472.  
  473.      (defvar emacs-lisp-mode-map () "")
  474.      
  475.      (if emacs-lisp-mode-map
  476.          ()
  477.        (setq emacs-lisp-mode-map (make-sparse-keymap))
  478.        (define-key emacs-lisp-mode-map "\e\C-x" 'eval-defun)
  479.        (lisp-mode-commands emacs-lisp-mode-map))
  480.  
  481.    Finally, here is the complete major mode function definition for
  482. Emacs Lisp mode.
  483.  
  484.      (defun emacs-lisp-mode ()
  485.        "Major mode for editing Lisp code to run in Emacs.
  486.      Commands:
  487.      Delete converts tabs to spaces as it moves back.
  488.      Blank lines separate paragraphs.  Semicolons start comments.
  489.      \\{emacs-lisp-mode-map}
  490.  
  491.      Entry to this mode runs the hook `emacs-lisp-mode-hook'."
  492.        (interactive)
  493.        (kill-all-local-variables)
  494.        (use-local-map emacs-lisp-mode-map)    ; This provides the local keymap.
  495.        (set-syntax-table emacs-lisp-mode-syntax-table)
  496.  
  497.      (setq major-mode 'emacs-lisp-mode)     ; This is how `describe-mode'
  498.                                               ;   finds out what to describe.
  499.        (setq mode-name "Emacs-Lisp")          ; This goes into the mode line.
  500.        (lisp-mode-variables nil)              ; This define various variables.
  501.        (run-hooks 'emacs-lisp-mode-hook))     ; This permits the user to use a
  502.                                               ;   hook to customize the mode.
  503.  
  504. 
  505. File: elisp,  Node: Auto Major Mode,  Next: Mode Help,  Prev: Example Major Modes,  Up: Major Modes
  506.  
  507. How Emacs Chooses a Major Mode
  508. ------------------------------
  509.  
  510.    Based on information in the file name or in the file itself, Emacs
  511. automatically selects a major mode for the new buffer when a file is
  512. visited.
  513.  
  514.  - Command: fundamental-mode
  515.      Fundamental mode is a major mode that is not specialized for
  516.      anything in particular.  Other major modes are defined in effect
  517.      by comparison with this one--their definitions say what to change,
  518.      starting from Fundamental mode.  The `fundamental-mode' function
  519.      does *not* run any hooks, so it is not readily customizable.
  520.  
  521.  - Command: normal-mode &optional FIND-FILE
  522.      This function establishes the proper major mode and local variable
  523.      bindings for the current buffer.  First it calls `set-auto-mode',
  524.      then it runs `hack-local-variables' to parse, and bind or evaluate
  525.      as appropriate, any local variables.
  526.  
  527.      If the FIND-FILE argument to `normal-mode' is non-`nil',
  528.      `normal-mode' assumes that the `find-file' function is calling it.
  529.      In this case, it may process a local variables list at the end of
  530.      the file.  The variable `enable-local-variables' controls whether
  531.      to do so.
  532.  
  533.      If you run `normal-mode' yourself, the argument FIND-FILE is
  534.      normally `nil'.  In this case, `normal-mode' unconditionally
  535.      processes any local variables list.  *Note Local Variables in
  536.      Files: (emacs)File variables, for the syntax of the local
  537.      variables section of a file.
  538.  
  539.      `normal-mode' uses `condition-case' around the call to the major
  540.      mode function, so errors are caught and reported as a `File mode
  541.      specification error',  followed by the original error message.
  542.  
  543.  - User Option: enable-local-variables
  544.      This variable controls processing of local variables lists in files
  545.      being visited.  A value of `t' means process the local variables
  546.      lists unconditionally; `nil' means ignore them; anything else means
  547.      ask the user what to do for each file.  The default value is `t'.
  548.  
  549.  - User Option: enable-local-eval
  550.      This variable controls processing of `Eval:' in local variables
  551.      lists in files being visited.  A value of `t' means process them
  552.      unconditionally; `nil' means ignore them; anything else means ask
  553.      the user what to do for each file.  The default value is `maybe'.
  554.  
  555.  - Function: set-auto-mode
  556.      This function selects the major mode that is appropriate for the
  557.      current buffer.  It may base its decision on the value of the `-*-'
  558.      line, on the visited file name (using `auto-mode-alist'), or on the
  559.      value of a local variable).  However, this function does not look
  560.      for the `mode:' local variable near the end of a file; the
  561.      `hack-local-variables' function does that.  *Note How Major Modes
  562.      are Chosen: (emacs)Choosing Modes.
  563.  
  564.  - User Option: default-major-mode
  565.      This variable holds the default major mode for new buffers.  The
  566.      standard value is `fundamental-mode'.
  567.  
  568.      If the value of `default-major-mode' is `nil', Emacs uses the
  569.      (previously) current buffer's major mode for the major mode of a
  570.      new buffer.  However, if the major mode symbol has a `mode-class'
  571.      property with value `special', then it is not used for new buffers;
  572.      Fundamental mode is used instead.  The modes that have this
  573.      property are those such as Dired and Rmail that are useful only
  574.      with text that has been specially prepared.
  575.  
  576.  - Variable: initial-major-mode
  577.      The value of this variable determines the major mode of the initial
  578.      `*scratch*' buffer.  The value should be a symbol that is a major
  579.      mode command name.  The default value is `lisp-interaction-mode'.
  580.  
  581.  - Variable: auto-mode-alist
  582.      This variable contains an association list of file name patterns
  583.      (regular expressions; *note Regular Expressions::.) and
  584.      corresponding major mode functions.  Usually, the file name
  585.      patterns test for suffixes, such as `.el' and `.c', but this need
  586.      not be the case.  Each element of the alist looks like `(REGEXP .
  587.      mODE-FUNCTION)'.
  588.  
  589.      For example,
  590.  
  591.           (("^/tmp/fol/" . text-mode)
  592.            ("\\.texinfo$" . texinfo-mode)
  593.            ("\\.texi$" . texinfo-mode)
  594.  
  595.           ("\\.el$" . emacs-lisp-mode)
  596.            ("\\.c$" . c-mode)
  597.            ("\\.h$" . c-mode)
  598.            ...)
  599.  
  600.      When you visit a file whose *expanded* file name (*note File Name
  601.      Expansion::.) matches a REGEXP, `set-auto-mode' calls the
  602.      corresponding MODE-FUNCTION.  This feature enables Emacs to select
  603.      the proper major mode for most files.
  604.  
  605.      Here is an example of how to prepend several pattern pairs to
  606.      `auto-mode-alist'.  (You might use this sort of expression in your
  607.      `.emacs' file.)
  608.  
  609.           (setq auto-mode-alist
  610.             (append
  611.              ;; Filename starts with a dot.
  612.              '(("/\\.[^/]*$" . fundamental-mode)
  613.                ;; Filename has no dot.
  614.                ("[^\\./]*$" . fundamental-mode)
  615.                ("\\.C$" . c++-mode))
  616.              auto-mode-alist))
  617.  
  618.  - Function: hack-local-variables &optional FORCE
  619.      This function parses, and binds or evaluates as appropriate, any
  620.      local variables for the current buffer.
  621.  
  622.      The handling of `enable-local-variables' documented for
  623.      `normal-mode' actually takes place here.  The argument FORCE
  624.      reflects the argument FIND-FILE given to `normal-mode'.
  625.  
  626. 
  627. File: elisp,  Node: Mode Help,  Prev: Auto Major Mode,  Up: Major Modes
  628.  
  629. Getting Help about a Major Mode
  630. -------------------------------
  631.  
  632.    The `describe-mode' function is used to provide information about
  633. major modes.  It is normally called with `C-h m'.  The `describe-mode'
  634. function uses the value of `major-mode', which is why every major mode
  635. function needs to set the `major-mode' variable.
  636.  
  637.  - Command: describe-mode
  638.      This function displays the documentation of the current major mode.
  639.  
  640.      The `describe-mode' function calls the `documentation' function
  641.      using the value of `major-mode' as an argument.  Thus, it displays
  642.      the documentation string of the major mode function.  (*Note
  643.      Accessing Documentation::.)
  644.  
  645.  - Variable: major-mode
  646.      This variable holds the symbol for the current buffer's major
  647.      mode.  This symbol should be the name of the function that is
  648.      called to initialize the mode.  The `describe-mode' function uses
  649.      the documentation string of this symbol as the documentation of
  650.      the major mode.
  651.  
  652. 
  653. File: elisp,  Node: Minor Modes,  Next: Mode Line Format,  Prev: Major Modes,  Up: Modes
  654.  
  655. Minor Modes
  656. ===========
  657.  
  658.    A "minor mode" provides features that users may enable or disable
  659. independently of the choice of major mode.  Minor modes can be enabled
  660. individually or in combination.  Minor modes would be better named
  661. "Generally available, optional feature modes" except that such a name is
  662. unwieldy.
  663.  
  664.    A minor mode is not usually a modification of single major mode.  For
  665. example, Auto Fill mode may be used in any major mode that permits text
  666. insertion.  To be general, a minor mode must be effectively independent
  667. of the things major modes do.
  668.  
  669.    A minor mode is often much more difficult to implement than a major
  670. mode.  One reason is that you should be able to deactivate a minor mode
  671. and restore the environment of the major mode to the state it was in
  672. before the minor mode was activated.
  673.  
  674.    Often the biggest problem in implementing a minor mode is finding a
  675. way to insert the necessary hook into the rest of Emacs.  Minor mode
  676. keymaps make this easier.
  677.  
  678. * Menu:
  679.  
  680. * Minor Mode Conventions::      Tips for writing a minor mode.
  681. * Keymaps and Minor Modes::     How a minor mode can have its own keymap.
  682.  
  683. 
  684. File: elisp,  Node: Minor Mode Conventions,  Next: Keymaps and Minor Modes,  Up: Minor Modes
  685.  
  686. Conventions for Writing Minor Modes
  687. -----------------------------------
  688.  
  689.    There are conventions for writing minor modes just as there are for
  690. major modes.  Several of the major mode conventions apply to minor
  691. modes as well: those regarding the name of the mode initialization
  692. function, the names of global symbols, and the use of keymaps and other
  693. tables.
  694.  
  695.    In addition, there are several conventions that are specific to
  696. minor modes.
  697.  
  698.    * Make a variable whose name ends in `-mode' to represent the minor
  699.      mode.  Its value should enable or disable the mode (`nil' to
  700.      disable; anything else to enable.)  We call this the "mode
  701.      variable".
  702.  
  703.      This variable is used in conjunction with the `minor-mode-alist' to
  704.      display the minor mode name in the mode line.  It can also enable
  705.      or disable a minor mode keymap.  Individual commands or hooks can
  706.      also check the variable's value.
  707.  
  708.      If you want the minor mode to be enabled separately in each buffer,
  709.      make the variable buffer-local.
  710.  
  711.    * Define a command whose name is the same as the mode variable.  Its
  712.      job is to enable and disable the mode by setting the variable.
  713.  
  714.      The command should accept one optional argument.  If the argument
  715.      is `nil', it should toggle the mode (turn it on if it is off, and
  716.      off if it is on).  Otherwise, it should turn the mode on if the
  717.      argument is a positive integer, a symbol other than `nil' or `-',
  718.      or a list whose CAR is such an integer or symbol; it should turn
  719.      the mode off otherwise.
  720.  
  721.      Here is an example taken from the definition of `overwrite-mode'.
  722.      It shows the use of `overwrite-mode' as a variable which enables or
  723.      disables the mode's behavior.
  724.  
  725.           (setq overwrite-mode
  726.                 (if (null arg) (not overwrite-mode)
  727.                   (> (prefix-numeric-value arg) 0)))
  728.  
  729.    * Add an element to `minor-mode-alist' for each minor mode (*note
  730.      Mode Line Variables::.).  This element should be a list of the
  731.      following form:
  732.  
  733.           (MODE-VARIABLE STRING)
  734.  
  735.      Here MODE-VARIABLE is the variable that controls enablement of the
  736.      minor mode, and STRING is a short string, starting with a space,
  737.      to represent the mode in the mode line.  These strings must be
  738.      short so that there is room for several of them at once.
  739.  
  740.      When you add an element to `minor-mode-alist', use `assq' to check
  741.      for an existing element, to avoid duplication.  For example:
  742.  
  743.           (or (assq 'leif-mode minor-mode-alist)
  744.               (setq minor-mode-alist
  745.                     (cons '(leif-mode " Leif") minor-mode-alist)))
  746.  
  747. 
  748. File: elisp,  Node: Keymaps and Minor Modes,  Prev: Minor Mode Conventions,  Up: Minor Modes
  749.  
  750. Keymaps and Minor Modes
  751. -----------------------
  752.  
  753.    As of Emacs version 19, each minor mode can have its own keymap
  754. which is active when the mode is enabled.  *Note Active Keymaps::.  To
  755. set up a keymap for a minor mode, add an element to the alist
  756. `minor-mode-map-alist'.
  757.  
  758.    One use of minor mode keymaps is to modify the behavior of certain
  759. self-inserting characters so that they do something else as well as
  760. self-insert.  This is the only way to accomplish this in general, since
  761. there is no way to customize what `self-insert-command' does except in
  762. certain special cases (designed for abbrevs and Auto Fill mode).  (Do
  763. not try substituting your own definition of `self-insert-command' for
  764. the standard one.  The editor command loop handles this function
  765. specially.)
  766.  
  767.  - Variable: minor-mode-map-alist
  768.      This variable is an alist of elements element that look like this:
  769.  
  770.           (VARIABLE . KEYMAP)
  771.  
  772.      where VARIABLE is the variable which indicates whether the minor
  773.      mode is enabled, and KEYMAP is the keymap.  The keymap KEYMAP is
  774.      active whenever VARIABLE has a non-`nil' value.
  775.  
  776.      Note that elements of `minor-mode-map-alist' do not have the same
  777.      structure as elements of `minor-mode-alist'.  The map must be the
  778.      CDR of the element; a list with the map as the second element will
  779.      not do.
  780.  
  781.      What's more, the keymap itself must appear in the CDR.  It does not
  782.      work to store a variable in the CDR and make the map the value of
  783.      that variable.
  784.  
  785.      When more than one minor mode keymap is active, their order of
  786.      priority is the order of `minor-mode-map-alist'.  But you should
  787.      design minor modes so that they don't interfere with each other.
  788.      If you do this properly, the order will not matter.
  789.  
  790. 
  791. File: elisp,  Node: Mode Line Format,  Next: Hooks,  Prev: Minor Modes,  Up: Modes
  792.  
  793. Mode Line Format
  794. ================
  795.  
  796.    Each Emacs window (aside from minibuffer windows) includes a mode
  797. line which displays status information about the buffer displayed in the
  798. window.  The mode line contains information about the buffer such as its
  799. name, associated file, depth of recursive editing, and the major and
  800. minor modes of the buffer.
  801.  
  802.    This section describes how the contents of the mode line are
  803. controlled.  It is in the chapter on modes because much of the
  804. information displayed in the mode line relates to the enabled major and
  805. minor modes.
  806.  
  807.    `mode-line-format' is a buffer-local variable that holds a template
  808. used to display the mode line of the current buffer.  All windows for
  809. the same buffer use the same `mode-line-format' and the mode lines will
  810. appear the same (except perhaps for the percentage of the file scrolled
  811. off the top).
  812.  
  813.    The mode line of a window is normally updated whenever a different
  814. buffer is shown in the window, or when the buffer's modified-status
  815. changes from `nil' to `t' or vice-versa.  If you modify any of the
  816. variables referenced by `mode-line-format', you may want to force an
  817. update of the mode line so as to display the new information.
  818.  
  819.  - Function: force-mode-line-update
  820.      Force redisplay of the current buffer's mode line.
  821.  
  822.    The mode line is usually displayed in inverse video; see
  823. `mode-line-inverse-video' in *Note Inverse Video::.
  824.  
  825. * Menu:
  826.  
  827. * Mode Line Data::        The data structure that controls the mode line.
  828. * Mode Line Variables::   Variables used in that data structure.
  829. * %-Constructs::          Putting information into a mode line.
  830.  
  831. 
  832. File: elisp,  Node: Mode Line Data,  Next: Mode Line Variables,  Prev: Mode Line Format,  Up: Mode Line Format
  833.  
  834. The Data Structure of the Mode Line
  835. -----------------------------------
  836.  
  837.    The mode line contents are controlled by a data structure of lists,
  838. strings, symbols and numbers kept in the buffer-local variable
  839. `mode-line-format'.  The data structure is called a "mode line
  840. construct", and it is built in recursive fashion out of simpler mode
  841. line constructs.
  842.  
  843.  - Variable: mode-line-format
  844.      The value of this variable is a mode line construct with overall
  845.      responsibility for the mode line format.  The value of this
  846.      variable controls which other variables are used to form the mode
  847.      line text, and where they appear.
  848.  
  849.    A mode line construct may be as simple as a fixed string of text, but
  850. it usually specifies how to use other variables to construct the text.
  851. Many of these variables are themselves defined to have mode line
  852. constructs as their values.
  853.  
  854.    The default value of `mode-line-format' incorporates the values of
  855. variables such as `mode-name' and `minor-mode-alist'.  Because of this,
  856. very few modes need to alter `mode-line-format'.  For most purposes, it
  857. is sufficient to alter the variables referenced by `mode-line-format'.
  858.  
  859.    A mode line construct may be a list, cons cell, symbol, or string.
  860. If the value is a list, each element may be a list, a cons cell, a
  861. symbol, or a string.
  862.  
  863. `STRING'
  864.      A string as a mode line construct is displayed verbatim in the
  865.      mode line except for "`%'-constructs".  Decimal digits after the
  866.      `%' specify the field width for space filling on the right (i.e.,
  867.      the data is left justified).  *Note %-Constructs::.
  868.  
  869. `SYMBOL'
  870.      A symbol as a mode line construct stands for its value.  The value
  871.      of SYMBOL is used in place of SYMBOL unless SYMBOL is `t' or
  872.      `nil', or is void, in which case SYMBOL is ignored.
  873.  
  874.      There is one exception: if the value of SYMBOL is a string, it is
  875.      processed verbatim in that the `%'-constructs are not recognized.
  876.  
  877. `(STRING REST...) or (LIST REST...)'
  878.      A list whose first element is a string or list, means to
  879.      concatenate all the elements.  This is the most common form of
  880.      mode line construct.
  881.  
  882. `(SYMBOL THEN ELSE)'
  883.      A list whose first element is a symbol is a conditional.  Its
  884.      meaning depends on the value of SYMBOL.  If the value is non-`nil',
  885.      the second element of the list (THEN) is processed recursively as
  886.      a mode line element.  But if the value of SYMBOL is `nil', the
  887.      third element of the list (if there is one) is processed
  888.      recursively.
  889.  
  890. `(WIDTH REST...)'
  891.      A list whose first element is an integer specifies truncation or
  892.      padding of the results of REST.  The remaining elements REST are
  893.      processed recursively as mode line constructs and concatenated
  894.      together.  Then the result is space filled (if WIDTH is positive)
  895.      or truncated (to -WIDTH columns, if WIDTH is negative) on the
  896.      right.
  897.  
  898.      For example, the usual way to show what percentage of a buffer is
  899.      above the top of the window is to use a list like this: `(-3 .
  900.      "%p")'.
  901.  
  902.    If you do alter `mode-line-format' itself, the new value should use
  903. all the same variables that are used by the default value, rather than
  904. duplicating their contents or displaying the information in another
  905. fashion.  This permits customizations made by the user, by libraries
  906. (such as `display-time') or by major modes via changes to those
  907. variables remain effective.
  908.  
  909.    Here is an example of a `mode-line-format' that might be useful for
  910. `shell-mode' since it contains the hostname and default directory.
  911.  
  912.      (setq mode-line-format
  913.        (list ""
  914.         'mode-line-modified
  915.         "%b--"
  916.         (getenv "HOST")      ; One element is not constant.
  917.         ":"
  918.         'default-directory
  919.         "   "
  920.         'global-mode-string
  921.         "   %[(" 'mode-name
  922.         'minor-mode-alist
  923.         "%n"
  924.         'mode-line-process
  925.         ")%]----"
  926.         '(-3 . "%p")
  927.         "-%-"))
  928.  
  929. 
  930. File: elisp,  Node: Mode Line Variables,  Next: %-Constructs,  Prev: Mode Line Data,  Up: Mode Line Format
  931.  
  932. Variables Used in the Mode Line
  933. -------------------------------
  934.  
  935.    This section describes variables incorporated by the standard value
  936. of `mode-line-format' into the text of the mode line.  There is nothing
  937. inherently special about these variables; any other variables could
  938. have the same effects on the mode line if `mode-line-format' were
  939. changed to use them.
  940.  
  941.  - Variable: mode-line-modified
  942.      This variable holds the value of the mode-line construct that
  943.      displays whether the current buffer is modified.
  944.  
  945.      The default value of `mode-line-modified' is `("--%1*%1*-")'.
  946.      This means that the mode line displays `--**-' if the buffer is
  947.      modified, `-----' if the buffer is not modified, and `--%%-' if
  948.      the buffer is read only.
  949.  
  950.      Changing this variable does not force an update of the mode line.
  951.  
  952.  - Variable: mode-line-buffer-identification
  953.      This variable identifies the buffer being displayed in the window.
  954.      Its default value is `Emacs: %17b', which means that it displays
  955.      `Emacs:' followed by the buffer name.  You may want to change this
  956.      in modes such as Rmail that do not behave like a "normal" Emacs.
  957.  
  958.  - Variable: global-mode-string
  959.      This variable holds a string that is displayed in the mode line.
  960.      The command `display-time' puts the time and load in this variable.
  961.      The `%M' construct substitutes the value of `global-mode-string',
  962.      but this is obsolete, since the variable is included directly in
  963.      the mode line.
  964.  
  965.  - Variable: mode-name
  966.      This buffer-local variable holds the "pretty" name of the current
  967.      buffer's major mode.  Each major mode should set this variable so
  968.      that the mode name will appear in the mode line.
  969.  
  970.  - Variable: minor-mode-alist
  971.      This variable holds an association list whose elements specify how
  972.      the mode line should indicate that a minor mode is active.  Each
  973.      element of the `minor-mode-alist' should be a two-element list:
  974.  
  975.           (MINOR-MODE-VARIABLE MODE-LINE-STRING)
  976.  
  977.      The string MODE-LINE-STRING is included in the mode line when the
  978.      value of MINOR-MODE-VARIABLE is non-`nil' and not otherwise.
  979.      These strings should begin with spaces so that they don't run
  980.      together.  Conventionally, the MINOR-MODE-VARIABLE for a specific
  981.      mode is set to a non-`nil' value when that minor mode is activated.
  982.  
  983.      The default value of `minor-mode-alist' is:
  984.  
  985.           minor-mode-alist
  986.           => ((abbrev-mode " Abbrev")
  987.               (overwrite-mode " Ovwrt")
  988.               (auto-fill-function " Fill")
  989.               (defining-kbd-macro " Def"))
  990.  
  991.      (In earlier Emacs versions, `auto-fill-function' was called
  992.      `auto-fill-hook'.)
  993.  
  994.      `minor-mode-alist' is not buffer-local.  The variables mentioned
  995.      in the alist should be buffer-local if the minor mode can be
  996.      enabled separately in each buffer.
  997.  
  998.  - Variable: mode-line-process
  999.      This buffer-local variable contains the mode line information on
  1000.      process status in modes used for communicating with subprocesses.
  1001.      It is displayed immediately following the major mode name, with no
  1002.      intervening space.  For example, its value in the `*shell*' buffer
  1003.      is `(": %s")', which allows the shell to display its status along
  1004.      with the major mode as: `(Shell: run)'.  Normally this variable is
  1005.      `nil'.
  1006.  
  1007.  - Variable: default-mode-line-format
  1008.      This variable holds the default `mode-line-format' for buffers
  1009.      that do not override it.  This is the same as `(default-value
  1010.      'mode-line-format)'.
  1011.  
  1012.      The default value of `default-mode-line-format' is:
  1013.  
  1014.           (""
  1015.            mode-line-modified
  1016.            mode-line-buffer-identification
  1017.            "   "
  1018.            global-mode-string
  1019.            "   %[("
  1020.            mode-name
  1021.            minor-mode-alist
  1022.            "%n"
  1023.            mode-line-process
  1024.            ")%]----"
  1025.            (-3 . "%p")
  1026.            "-%-")
  1027.  
  1028. 
  1029. File: elisp,  Node: %-Constructs,  Prev: Mode Line Variables,  Up: Mode Line Format
  1030.  
  1031. `%'-Constructs in the Mode Line
  1032. -------------------------------
  1033.  
  1034.    The following table lists the recognized `%'-constructs and what
  1035. they mean.
  1036.  
  1037. `%b'
  1038.      the current buffer name, using the `buffer-name' function.
  1039.  
  1040. `%f'
  1041.      the visited file name, using the `buffer-file-name' function.
  1042.  
  1043. `%*'
  1044.      `%' if the buffer is read only (see `buffer-read-only');
  1045.      `*' if the buffer is modified (see `buffer-modified-p');
  1046.      `-' otherwise.
  1047.  
  1048. `%s'
  1049.      the status of the subprocess belonging to the current buffer, using
  1050.      `process-status'.
  1051.  
  1052. `%p'
  1053.      the percent of the buffer above the top of window, or `Top',
  1054.      `Bottom' or `All'.
  1055.  
  1056. `%n'
  1057.      `Narrow' when narrowing is in effect; nothing otherwise (see
  1058.      `narrow-to-region' in *Note Narrowing::).
  1059.  
  1060. `%['
  1061.      an indication of the depth of recursive editing levels (not
  1062.      counting minibuffer levels): one `[' for each editing level.
  1063.  
  1064. `%]'
  1065.      one `]' for each recursive editing level (not counting minibuffer
  1066.      levels).
  1067.  
  1068. `%%'
  1069.      the character `%'--this is how to include a literal `%' in a
  1070.      string in which `%'-constructs are allowed.
  1071.  
  1072. `%-'
  1073.      dashes sufficient to fill the remainder of the mode line.
  1074.  
  1075.    The following two `%'-constructs are still supported but are
  1076. obsolete since use of the `mode-name' and `global-mode-string'
  1077. variables will produce the same results.
  1078.  
  1079. `%m'
  1080.      the value of `mode-name'.
  1081.  
  1082. `%M'
  1083.      the value of `global-mode-string'.  Currently, only `display-time'
  1084.      modifies the value of `global-mode-string'.
  1085.  
  1086. 
  1087. File: elisp,  Node: Hooks,  Prev: Mode Line Format,  Up: Modes
  1088.  
  1089. Hooks
  1090. =====
  1091.  
  1092.    A "hook" is a variable where you can store a function or functions
  1093. to be called on a particular occasion by an existing program.  Emacs
  1094. provides lots of hooks for the sake of customization.  Most often, hooks
  1095. are set up in the `.emacs' file, but Lisp programs can set them also.
  1096. *Note Standard Hooks::, for a list of standard hook variables.
  1097.  
  1098.    Most of the hooks in Emacs are "normal hooks".  These variables
  1099. contain lists of functions to be called with no arguments.  The reason
  1100. most hooks are normal hooks is so that you can use them in a uniform
  1101. way.  You can always tell when a hook is a normal hook, because its
  1102. name ends in `-hook'.
  1103.  
  1104.    The recommended way to add a hook function to a normal hook is by
  1105. calling `add-hook' (see below).  The hook functions may be any of the
  1106. valid kinds of functions that `funcall' accepts (*note What Is a
  1107. Function::.).  Most normal hook variables are initially void;
  1108. `add-hook' knows how to deal with this.
  1109.  
  1110.    As for abnormal hooks, those whose names end in `-function' have a
  1111. value which is a single function.  Those whose names end in `-hooks'
  1112. have a value which is a list of functions.  Any hook which is abnormal
  1113. is abnormal because a normal hook won't do the job; either the
  1114. functions are called with arguments, or their values are meaningful.
  1115. The name shows you that the hook is abnormal and you need to look up
  1116. how to use it properly.
  1117.  
  1118.    Most major modes run hooks as the last step of initialization.  This
  1119. makes it easy for a user to customize the behavior of the mode, by
  1120. overriding the local variable assignments already made by the mode.  But
  1121. hooks may also be used in other contexts.  For example, the hook
  1122. `suspend-hook' runs just before Emacs suspends itself (*note Suspending
  1123. Emacs::.).
  1124.  
  1125.    For example, you can put the following expression in your `.emacs'
  1126. file if you want to turn on Auto Fill mode when in Lisp Interaction
  1127. mode:
  1128.  
  1129.      (add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
  1130.  
  1131.    The next example shows how to use a hook to customize the way Emacs
  1132. formats C code.  (People often have strong personal preferences for one
  1133. format compared to another.)  Here the hook function is an anonymous
  1134. lambda expression.
  1135.  
  1136.      (add-hook 'c-mode-hook
  1137.        (function (lambda ()
  1138.                    (setq c-indent-level 4
  1139.                          c-argdecl-indent 0
  1140.                          c-label-offset -4
  1141.                          c-continued-statement-indent 0
  1142.                          c-brace-offset 0
  1143.                          comment-column 40))))
  1144.      
  1145.      (setq c++-mode-hook c-mode-hook)
  1146.  
  1147.    Finally, here is an example of how to use the Text mode hook to
  1148. provide a customized mode line for buffers in Text mode, displaying the
  1149. default directory in addition to the standard components of the mode
  1150. line.  (This may cause the mode line to run out of space if you have
  1151. very long file names or display the time and load.)
  1152.  
  1153.      (add-hook 'text-mode-hook
  1154.        (function (lambda ()
  1155.                    (setq mode-line-format
  1156.                          '(mode-line-modified
  1157.                            "Emacs: %14b"
  1158.                            "  "
  1159.                            default-directory
  1160.                            " "
  1161.                            global-mode-string
  1162.                            "%[("
  1163.                            mode-name
  1164.                            minor-mode-alist
  1165.                            "%n"
  1166.                            mode-line-process
  1167.                            ") %]---"
  1168.                            (-3 . "%p")
  1169.                            "-%-")))))
  1170.  
  1171.    At the appropriate time, Emacs uses the `run-hooks' function to run
  1172. particular hooks.  This function calls the hook functions you have
  1173. added with `add-hooks'.
  1174.  
  1175.  - Function: run-hooks &rest HOOKVAR
  1176.      This function takes one or more hook names as arguments and runs
  1177.      each one in turn.  Each HOOKVAR argument should be a symbol that
  1178.      is a hook variable.  These arguments are processed in the order
  1179.      specified.
  1180.  
  1181.      If a hook variable has a non-`nil' value, that value may be a
  1182.      function or a list of functions.  If the value is a function
  1183.      (either a lambda expression or a symbol with a function
  1184.      definition), it is called.  If it is a list, the elements are
  1185.      called, in order.  The hook functions are called with no arguments.
  1186.  
  1187.      For example:
  1188.  
  1189.           (run-hooks 'emacs-lisp-mode-hook)
  1190.  
  1191.      Major mode functions use this function to call any hooks defined
  1192.      by the user.
  1193.  
  1194.  - Function: add-hook HOOK FUNCTION &optional APPEND
  1195.      This function is the handy way to add function FUNCTION to hook
  1196.      variable HOOK.  For example,
  1197.  
  1198.           (add-hook 'text-mode-hook 'my-text-hook-function)
  1199.  
  1200.      adds `my-text-hook-function' to the hook called `text-mode-hook'.
  1201.  
  1202.      It is best to design your hook functions so that the order in
  1203.      which they are executed does not matter.  Any dependence on the
  1204.      order is "asking for trouble."  However, the order is predictable:
  1205.      normally, FUNCTION goes at the front of the hook list, so it will
  1206.      be executed first (barring another `add-hook' call).
  1207.  
  1208.      If the optional argument APPEND is non-`nil', the new hook
  1209.      function goes at the end of the hook list and will be executed
  1210.      last.
  1211.  
  1212.